---
title: Expectation Initializers
layout: page
pageOrder: 6
section: 'Mock Server'
subsection: true
sitemap:
  priority: 0.7
  changefreq: 'monthly'
  lastmod: 2019-11-10T08:00:00+01:00
---

<p>To ensure expectations are available as soon as MockServer is started it is possible to use an expectation initializer, there are three options:</p>

<ul>
    <li><strong><a href="#expectation_initializer_class">initializer class</a></strong> loaded from the classpath to construct an array of expectations</li>
    <li><strong><a href="#expectation_initializer_json">initializer JSON file</a></strong> loaded from the filesystem containing a serialised array of expectations</li>
    <li><strong><a href="#maven_plugin_expectation_initializer_class">maven plugin initializer class</a></strong> loaded from the classpath to add expectations using the MockServerClient</li>
</ul>

<p><strong>Note:</strong> all three options require the class or file to be available to the MockServer, i.e. in the local classpath or filesystem.  To remotely initialise the MockServer a client is required to connect to the MockServer after it has started and submit one or more expectations.</p>

<a id="expectation_initializer_class" class="anchor" href="#expectation_initializer_class">&nbsp</a>

<h2>Expectation Initializer Class</h2>

<p>MockServer expectations can be initialized when the MockServer starts, using a class, by specified the <strong>initializationClass</strong> configuration property as described in the <a href="/mock_server/configuration_properties.html#button_configuration_initialization_class">Configuration Properties</a> page, for example:</p>
<pre class="prettyprint lang-java code"><code class="code">System.setProperty("mockserver.initializationClass", ExpectationInitializerExample.class.getName());
int mockServerPort = new ClientAndServer().getLocalPort();</code></pre>

<p>The class must implement the <strong>org.mockserver.server.initialize.ExpectationInitializer</strong> interface and have a default constructor with zero arguments, for example:</p>

<pre class="prettyprint lang-java code"><code class="code">public class ExpectationInitializerExample implements ExpectationInitializer {
    @Override
    public Expectation[] initializeExpectations() {
        return new Expectation[]{
            new Expectation(
                request()
                    .withPath("/simpleFirst")
            )
                .thenRespond(
                response()
                    .withBody("some first response")
            ),
            new Expectation(
                request()
                    .withPath("/simpleSecond")
            )
                .thenRespond(
                response()
                    .withBody("some second response")
            )
        };
    }
}</code></pre>

<a id="expectation_initializer_json" class="anchor" href="#expectation_initializer_json">&nbsp;</a>

<h2>Expectation Initializer JSON</h2>

<p>MockServer expectations can be initialized when the MockServer starts, using a JSON file, by specified the <strong>initializationJsonPath</strong> configuration property as described in the <a href="/mock_server/configuration_properties.html#button_configuration_initialization_json_path">Configuration Properties</a> page, for example:</p>
<pre><code class="code">java -Dmockserver.initializationJsonPath=<span class="string_literal">"org/mockserver/server/initialize/initializerJson.json"</span> -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort <span class="numeric_literal">1080</span> -logLevel INFO</code></pre>

<p><strong>initializationJsonPath</strong> supports:</p>

<ul>
    <li>related or absolute paths</li>
    <li>both filesystem and classpath locations</li>
    <li>multiple files by using glob patterns that can expand a wildcard pattern into a list of paths that match the given pattern using characters such as *, **, ?, [] and {}, for more details see <a href="#expectation_initializer_json_glob_patterns">glob patterns</a></li>
</ul>

<p>The JSON file should contain an array of serialised expectations, for example:</p>

<pre class="prettyprint lang-java code"><code class="code">[
  {
    "httpRequest": {
      "path": "/simpleFirst"
    },
    "httpResponse": {
      "body": "some first response"
    }
  },
  {
    "httpRequest": {
      "path": "/simpleSecond"
    },
    "httpResponse": {
      "body": "some second response"
    }
  }
]</code></pre>

<a id="expectation_initializer_json_glob_patterns" class="anchor" href="#expectation_initializer_json_glob_patterns">&nbsp;</a>

<h3>Multiple Files (Glob Patterns)</h3>

<ul>
    <li>The * character matches zero or more characters of a name component without crossing directory boundaries.</li>
    <li>The ** characters matches zero or more characters crossing directory boundaries.</li>
    <li>The ? character matches exactly one character of a name component.</li>
    <li>The backslash character (\) is used to escape characters that would otherwise be interpreted as special characters. The expression \\ matches a single backslash and "\{" matches a left brace for example.</li>
    <li>The [ ] characters are a bracket expression that match a single character of a name component out of a set of characters. For example, [abc] matches "a", "b", or "c". The hyphen (-) may be used to specify a range so [a-z] specifies a range that matches from "a" to "z" (inclusive). These forms can be mixed so [abce-g] matches "a", "b", "c", "e", "f" or "g". If the character after the [ is a ! then it is used for negation so [!a-c] matches any character except "a", "b", or "c".</li>
    <li>Within a bracket expression the *, ? and \ characters match themselves. The (-) character matches itself if it is the first character within the brackets, or the first character after the ! if negating.</li>
    <li>The { } characters are a group of subpatterns, where the group matches if any subpattern in the group matches. The "," character is used to separate the subpatterns. Groups cannot be nested.</li>
</ul>


<a id="expectation_initializer_json_file_watcher" class="anchor" href="#expectation_initializer_json_file_watcher">&nbsp;</a>

<h2>Expectation Initializer JSON File Watcher</h2>

<p>If a JSON expectation initializer is specified a file watcher can be enabled that watches for changes in the expectation initializer and updates the expectations when the file is modified.  Changes are detected at most after 5 seconds if the file contents has changed.</p>
<p>If enabled the initialization json file will be watched for changes, any changes found will result in expectations being created, remove or updated by matching against their key.</p>
<p>If duplicate keys exist only the first duplicate key in the file will be processed and all duplicates except the first duplicate will be ignored.</p>
<p>The order of expectations in the file is the order in which they are created if they are new, however, re-ordering existing expectations does not change the order they are matched against incoming requests.</p>

<pre class="prettyprint lang-javascript code"><code class="code">MOCKSERVER_WATCH_INITIALIZATION_JSON=true \
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverInitialization.json \
java -jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO</code></pre>

<p>or</p>

<pre class="prettyprint lang-javascript code"><code class="code">java \
-Dmockserver.watchInitializationJson=true \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO</code></pre>

{% include_subpage _includes/clustering.html %}

<a id="maven_plugin_expectation_initializer_class" class="anchor" href="#maven_plugin_expectation_initializer_class">&nbsp;</a>

<h2>Maven Plugin Expectation Initializer Class</h2>

<p>If the MockServer is started using the <a href="/mock_server/running_mock_server.html#maven_plugin">Maven Plugin</a> a <strong>initializationClass</strong> property can be specified to initialize expectations, when the MockServer starts.</p>
<p><strong>Note:</strong> the plugin must be started during the <strong>process-test-classes</strong> to ensure that the initialization class has been compiled from either <strong>src/main/java</strong> or <strong>src/test/java</strong> locations. In addition the initializer can only be used with <strong>start</strong> and <strong>run</strong> goals, it will not work with the <strong>runForked</strong> goal as a JVM is forked with a separate classpath. (required: false, default: false)</p>

<p>The following section from a pom.xml shows how the <a href="/mock_server/running_mock_server.html#maven_plugin">Maven Plugin</a> can be configured to specify an <strong>initializationClass</strong>:</p>

<pre><code class="code xml">&lt;<span class="element">plugin</span>&gt;
    &lt;<span class="element">groupId</span>&gt;<span class="element_value">org.mock-server</span>&lt;/<span class="element">groupId</span>&gt;
    &lt;<span class="element">artifactId</span>&gt;<span class="element_value">mockserver-maven-plugin</span>&lt;/<span class="element">artifactId</span>&gt;
    &lt;<span class="element">version</span>&gt;<span class="element_value">{{ site.mockserver_version }}</span>&lt;/<span class="element">version</span>&gt;
    &lt;<span class="element">configuration</span>&gt;
        &lt;<span class="element">serverPort</span>&gt;<span class="element_value">1080</span>&lt;/<span class="element">serverPort</span>&gt;
        &lt;<span class="element">logLevel</span>&gt;<span class="element_value">DEBUG</span>&lt;/<span class="element">logLevel</span>&gt;
        &lt;<span class="element">initializationClass</span>&gt;<span class="element_value">org.mockserver.maven.ExampleInitializationClass</span>&lt;/<span class="element">initializationClass</span>&gt;
    &lt;/<span class="element">configuration</span>&gt;
    &lt;<span class="element">executions</span>&gt;
        &lt;<span class="element">execution</span>&gt;
            &lt;<span class="element">id</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">id</span>&gt;
            &lt;<span class="element">phase</span>&gt;<span class="element_value">process-test-classes</span>&lt;/<span class="element">phase</span>&gt;
            &lt;<span class="element">goals</span>&gt;
                &lt;<span class="element">goal</span>&gt;<span class="element_value">start</span>&lt;/<span class="element">goal</span>&gt;
            &lt;/<span class="element">goals</span>&gt;
        &lt;/<span class="element">execution</span>&gt;
        &lt;<span class="element">execution</span>&gt;
            &lt;<span class="element">id</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">id</span>&gt;
            &lt;<span class="element">phase</span>&gt;<span class="element_value">verify</span>&lt;/<span class="element">phase</span>&gt;
            &lt;<span class="element">goals</span>&gt;
                &lt;<span class="element">goal</span>&gt;<span class="element_value">stop</span>&lt;/<span class="element">goal</span>&gt;
            &lt;/<span class="element">goals</span>&gt;
        &lt;/<span class="element">execution</span>&gt;
    &lt;/<span class="element">executions</span>&gt;
&lt;/<span class="element">plugin</span>&gt;</code></pre>

<p>The class must implement the <strong>org.mockserver.client.initialize.PluginExpectationInitializer</strong> interface and have a default constructor with zero arguments, for example:</p>

<pre class="prettyprint lang-java code"><code class="code">public class ExampleInitializationClass implements PluginExpectationInitializer {

    @Override
    public void initializeExpectations(MockServerClient mockServerClient) {
        mockServerClient
                .when(
                        request()
                                .withPath("/simpleFirst")
                )
                .respond(
                        response()
                                .withBody("some first response")
                );
        mockServerClient
                .when(
                        request()
                                .withPath("/simpleSecond")
                )
                .respond(
                        response()
                                .withBody("some second response")
                );
    }
}</code></pre>

{% include_subpage _includes/initializer_persistence_configuration.html %}
